{**Core interface unit.
functions, structures and types exported by engine Core (core.dll). they might be used in plugins to access each other,
process events, errors etc.}
unit CoreI;

interface
uses sdl;
const
Core_Lib = 'core'; //**< Name of the Core DLL (e.g. 'core.dll' under Windows
//**set of core state modes
type TCore_State=(
//**Use this to indicate that main loop must be terminated
Core_Terminating=0,
//**all subsystems must suspend their work. this mode sets when main game window loses focus.
core_suspended=1,
//**most subsystems such as world must pause their work
core_paused = 2,
//**game process is going on
core_running = 3,
//**pass this to Core_SetState() to restore last core state
Core_LastState=255
                  );

                  const
                  //**Error while initializing subsystems
ECore_Init=1;
//**Error while main game loop is executing
ECore_Main=2;

//**Log levels passed to Log_Write and Log_WriteF routines
                                                          type TLogLevel=(
//**Critical error! Inform user and terminate program
ll_critical=0,
//**some error, but game can execute
ll_error=1,
//**warning (e.g. accessing to not existing structure), might be usefull when testing scripts
ll_warn=2,
//**Information about what's on (Loading plugins, Entering main game loop etc), to trace where error appears
ll_info=3,
//**special information only for debug purposes
ll_debug=4
);

{**This type is used in Core_RegisterErrorHandler procedure to get information about errors happened to process it.
     @param(str specifies error message, might be changed inside function)
     @param(Code specifies error code, might be changed inside function)
     @return(@false when more error processing not needed, @true othervise (in this case next error handler if exists will be called))
}
     type TCore_ErrorHandler=function(var str:PChar; var code:cardinal):boolean; cdecl;

{**this structure represents info about supported interface, it must be filled inside plugin Plugin_GetInfo()
exported function, each plugin can implement any number of interfaces}
     type PPluginInfo=^TPluginInfo;
TPluginInfo=packed record
GUID:TGUID; //**GUID for the supported interface
InterfaceStruct:pointer; //**pointer to structure representing this interface
           Name:PChar; //**symbolical name of the interface (used in error and info messages)
Init:procedure; cdecl; //**Pointer to the Init procedure which will be called by Core when interface will be needed
free:procedure;cdecl; //**Pointer to the Free procedure which will be called by Core when interface will be not needed anymore
end;
{**this function must be exported by plugin, to Core can manage it and its interfaces.
@param(info array with PPluginInfo structures representing each supported interface)
@param(Length - number of elements in info array)
}
TCore_Plugin_GetInfo=procedure(var info:PPluginInfo; var Length:cardinal); cdecl;
{**Prototype to Event Handler function, passed to Core_RegisterEventHandler.
@param(Event SDL structure with event to process)
@returns(@false if there is no need to process this event by other event handlers, @true if opposit)
}
TCore_EventHandler=function(Event:TSDL_Event):boolean; cdecl;
TTimerID = cardinal;
TTimerProc=function(const Timer:TTimerID; const data:pointer):integer; cdecl;
{**Raises error to be processed by error handlers queue.
@param(str error message)
@param(code error code)
}
procedure Core_Error(str:PChar; code:cardinal); cdecl; external Core_Lib;
{**Registers specified error handler function in error handlers queue.
@param(Handler pointer to error handler function to register)
}
procedure Core_RegisterErrorHandler(handler:TCore_ErrorHandler); cdecl; external Core_Lib;
{**removes specified function from error handler queue.
@param(Handeler Function to remove)
}
procedure Core_UnregisterErrorHandler(handler:TCore_ErrorHandler); cdecl; external Core_Lib;
{**writes message to the game log.
@param(Message Message to write)
@param(Level Minimal log level at which message will be written. If current log level is less than specified, message will be omitted)
}
Procedure Log_Write(const message:PChar; level:TLogLevel); cdecl; external Core_Lib;
{**writes formatted message to the game log.
@param(Message template to be formatted)
@param(Level Minimal log level at which message will be written. If current log level is less than specified, message will be omitted)
@param(args - any number  of arguments to be used in format template)
}
Procedure Log_WriteF(const message:PChar; level:TLogLevel; args:array of const); cdecl; external Core_Lib;
//**Initializes core and all plugins. Might be called only from Engine loader (e.g. Engine.exe)
procedure Core_Init; cdecl; external Core_Lib;
//**Executes core main loop. Might be called only from Engine loader (e.g. Engine.exe)
           procedure Core_Main; cdecl; external Core_Lib;
//**Closes core and all subsystems. Might be called only from engine loader (e.g. engine.exe)
           Procedure Core_Close; cdecl; external Core_Lib;
{**Use this function to receive needed interface, or raise an error if its not exists or is not accessible.
@param(GUID GUID of required interface)
@returns(Pointer to specified interface, or @nil if it not exists. In this case, function raises an error)
}
           Function Core_RequirePlugin(const GUID:TGUID):pointer; cdecl; external Core_Lib;
           {**checks if specified interface exists (is supported by one of loaded plugins).
           @param(GUID GUID of interface to check)
           @returns(@true if interface is supported, @false othervise)
           }
           Function Core_PluginExists(const GUID:TGUID):boolean; cdecl; external Core_Lib;
           {**Registers event handler function in event handlers queue. Use this to receive and process needed events.
           @param(EventType must be one of SDL event types or types, defined in common.pas)
           @param(EventHandler pointer to the event handler function)
           }
           Procedure Core_RegisterEventHandler(const EventType:byte; EventHandler:TCore_EventHandler); cdecl; external Core_Lib;
           {**removes specified event handler function from the event handlers queue.
           @param(EventHandler pointer to event handler to remove)
           }
           procedure Core_UnregisterEventHandler(const handler:TCore_EventHandler); cdecl; external Core_Lib;
           {**Use this to receive current Core state.
           @returns(Current core state)
           }
           function Core_GetState:TCore_State; cdecl; external Core_Lib;
           {**Use this to set the core state.
           @param(State new core state)
           }
           Procedure Core_SetState(state:TCore_State); cdecl; external Core_Lib;
           {@Returns (time elapsed while core is actually running (excluding time when core was suspended or paused))}
           Function Core_GetTime:Int64; cdecl; external Core_Lib;
Function Core_AddTimer(const interval:cardinal; TimerProc:TTimerProc; data:pointer):TTimerID; cdecl; external Core_Lib;
procedure Core_RemoveTimer(const timer:TTimerID); cdecl; external Core_Lib;
Procedure Core_ScanForPlugins(); cdecl; external Core_Lib;
Procedure Core_FreePlugins(); external Core_Lib;
           implementation

end.
